home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kextsock.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  37.5 KB  |  1,111 lines

  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (C) 2000-2004 Thiago Macieira <thiago.macieira@kdemail.net>
  4.  *
  5.  *  This library is free software; you can redistribute it and/or
  6.  *  modify it under the terms of the GNU Library General Public
  7.  *  License as published by the Free Software Foundation; either
  8.  *  version 2 of the License, or (at your option) any later version.
  9.  *
  10.  *  This library is distributed in the hope that it will be useful,
  11.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  *  Library General Public License for more details.
  14.  *
  15.  *  You should have received a copy of the GNU Library General Public License
  16.  *  along with this library; see the file COPYING.LIB.  If not, write to
  17.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  *  Boston, MA 02110-1301, USA.
  19.  */
  20. #ifndef KEXTSOCK_H
  21. #define KEXTSOCK_H
  22.  
  23. #include "kdelibs_export.h"
  24.  
  25. #ifdef Q_OS_UNIX
  26.  
  27. #include <sys/time.h>
  28.  
  29. #include <qstring.h>
  30. #include <qptrlist.h>
  31. #include <qiodevice.h>
  32.  
  33. #include "kbufferedio.h"
  34. #include "ksockaddr.h"
  35.  
  36. /* External reference to netdb.h */
  37. struct addrinfo;
  38. struct kde_addrinfo;
  39. class KAddressInfo;        /* our abstraction of it */
  40. class QSocketNotifier;
  41.  
  42. /*
  43.  * This is extending QIODevice's error codes
  44.  *
  45.  * According to qiodevice.h, the last error is IO_UnspecifiedError
  46.  * These errors will never occur in functions declared in QIODevice
  47.  * (except open, but you shouldn't call open)
  48.  */
  49. #define IO_ListenError        (IO_UnspecifiedError+1)
  50. #define IO_AcceptError        (IO_UnspecifiedError+2)
  51. #define IO_LookupError        (IO_UnspecifiedError+3)
  52.  
  53. class KExtendedSocketPrivate;
  54. /**
  55.  * The extended socket class.
  56.  *
  57.  * This class should be used instead of KSocket whenever the user needs
  58.  * fine-grained control over the socket being created. Unlike KSocket, which
  59.  * does everything at once, without much intervention, KExtendedSocket allows
  60.  * intervention at every step of the process and the setting of parameters.
  61.  *
  62.  * This class allows for the creation of both server and client sockets. The
  63.  * only difference is that the passiveSocket flag must be passed either to
  64.  * the constructor or to setSocketFlags(). If passiveSocket is used, the class will
  65.  * enable functions listen() and accept() and related signals, and will
  66.  * also disable readBlock() and writeBlock().
  67.  *
  68.  * To create a Unix socket, one would pass flag unixSocket to the constructor
  69.  * or setSocketFlags(). The hostname and service/port can be set to whatever is
  70.  * necessary. If no hostname is given, but a service/port is, the socket created
  71.  * will be implementation dependant (usually in /tmp). In any other case, the
  72.  * fields will be concatenated.
  73.  *
  74.  * To create an Internet socket, inetSocket flag can be used. If, on the other
  75.  * hand a specific IP protocol is desired, ipv4Socket and/or ipv6Socket can be
  76.  * used.
  77.  *
  78.  * Note that the socket type selection flags are cumulative. One could select
  79.  * Unix and Internet sockets by using unixSocket | inetSocket. Or, for instance,
  80.  * to make sure only IPv4 and IPv6 sockets are selected, even if future implementations
  81.  * support newer IP protocols, ipv4Socket | ipv6Socket is your guy.
  82.  *
  83.  * @deprecated
  84.  *    This class is now deprecated. Please use the classes in KNetwork for
  85.  *    new programs. In particular, this class is replaced by KNetwork::KStreamSocket
  86.  *    and @ref KNetwork::KServerSocket.
  87.  *
  88.  * @author Thiago Macieira <thiago.macieira@kdemail.net>
  89.  * @short an extended socket
  90.  */
  91. class KDECORE_EXPORT KExtendedSocket: public KBufferedIO // public QObject, public QIODevice
  92. {
  93.   Q_OBJECT
  94.  
  95. public:
  96.   /**
  97.    * flags that can be passed down to the member functions
  98.    */
  99.   enum Flags
  100.   {
  101.     /* socket address families */
  102.     /*
  103.      * NOTE: if you change this, you have to change function valid_socket() as well
  104.      * These values are hard coded!
  105.      */
  106.     anySocket = 0x00,
  107.     knownSocket = 0x01,
  108.     unixSocket = knownSocket | 0x02,
  109.     inetSocket = knownSocket | 0x04,
  110.     ipv4Socket = inetSocket | 0x100,
  111.     ipv6Socket = inetSocket | 0x200,
  112.  
  113.     passiveSocket = 0x1000,    /* passive socket (i.e., one that accepts connections) */
  114.     canonName = 0x2000,        /* request that the canon name be found */
  115.     noResolve = 0x4000,        /* do not attempt to resolve, treat as numeric host */
  116.  
  117.     streamSocket = 0x8000,    /* request a streaming socket (e.g., TCP) */
  118.     datagramSocket = 0x10000,    /* request a datagram socket (e.g., UDP) */
  119.     rawSocket = 0x20000,    /* request a raw socket. This probably requires privileges */
  120.  
  121.     inputBufferedSocket = 0x200000, /* buffer input in this socket */
  122.     outputBufferedSocket = 0x400000, /* buffer output in this socket */
  123.     bufferedSocket = 0x600000    /* make this a fully buffered socket */
  124.   };
  125.  
  126.   /**
  127.    * status of the class
  128.    * The status are sequential. If a change to one status is requested,
  129.    * all the prior status will be passed and their actions, performed
  130.    */
  131.   enum SockStatus
  132.   {
  133.     // the numbers are scattered so that we leave room for future expansion
  134.     error = -1,            // invalid status!
  135.  
  136.     nothing = 0,        // no status, the class has just been created
  137.  
  138.     lookupInProgress = 50,    // lookup is in progress. Signals will be sent
  139.     lookupDone = 70,        // lookup has been done. Flags cannot be changed
  140.                 // from this point on
  141.  
  142.     created = 100,        // ::socket() has been called, a socket exists
  143.     bound = 140,        // socket has been bound
  144.  
  145.     connecting = 200,        // socket is connecting (not passiveSocket)
  146.     connected = 220,        // socket has connected (not passiveSocket)
  147.  
  148.     listening = 200,        // socket is listening (passiveSocket)
  149.     accepting = 220,        // socket is accepting (passiveSocket)
  150.  
  151.     closing = 350,        // socket is closing (delayed close)
  152.  
  153.     done = 400            // socket has been closed
  154.   };
  155.  
  156. public:
  157.   /**
  158.    * Creates an empty KExtendedSocket.
  159.    */
  160.   KExtendedSocket();
  161.  
  162.   /**
  163.    * Creates a socket with the given hostname and port.
  164.    *
  165.    * If this is a connecting (active) socket, the hostname and port specify
  166.    * the remote address to which we will connect.
  167.    *
  168.    * If this is a listening (passive) socket, the hostname and port specify
  169.    * the address to listen on. In order to listen on every interface
  170.    * available on this node, set @p host to QString::null. To let the operating
  171.    * system select a port, set it to 0.
  172.    *
  173.    * @sa setAddress
  174.    * @param host    the hostname
  175.    * @param port    the port number
  176.    * @param flags    flags
  177.    */
  178.   KExtendedSocket(const QString& host, int port, int flags = 0);
  179.  
  180.   /**
  181.    * Creates a socket with the given hostname and service.
  182.    *
  183.    * If this is a connecting (active) socket, the hostname and service specify
  184.    * the remote address to which we will connect.
  185.    *
  186.    * If this is a listening (passive) socket, the hostname and service specify
  187.    * the address to listen on. In order to listen on every interface
  188.    * available on this node, set @p host to QString::null. To let the operating
  189.    * system select a port, set the service to "0".
  190.    *
  191.    * @sa setAddress
  192.    * @param host    the hostname
  193.    * @param service    the service
  194.    * @param flags    flags
  195.    */
  196.   KExtendedSocket(const QString& host, const QString& service, int flags = 0);
  197.  
  198.   /**
  199.    * Destroys the socket, disconnecting if still connected and
  200.    * freeing any related resources still being kept.
  201.    */
  202.   virtual ~KExtendedSocket();
  203.  
  204.   /**
  205.    * Resets the socket, disconnecting if still connected and
  206.    * freeing any related resources still being kept.
  207.    * @since 3.1
  208.    */
  209.   void reset();
  210.  
  211.   /*
  212.    * --- status, flags and internal variables --- *
  213.    */
  214.  
  215.   /**
  216.    * Returns the class status.
  217.    * @return the class status
  218.    * @see ::SockStatus
  219.    */
  220.   int socketStatus() const;
  221.  
  222.   /**
  223.    * Returns the related system error code
  224.    * Except for IO_LookupError errors, these are codes found in
  225.    * errno
  226.    * @return the system error code
  227.    */
  228.   int systemError() const;
  229.  
  230.   /**
  231.    * Sets the given flags.
  232.    * @param flags    the flags to be set
  233.    * @return the new flags status, or -1 if flags can no longer be set
  234.    */
  235.   int setSocketFlags(int flags);
  236.  
  237.   /**
  238.    * Returns the current flags
  239.    * @return the current flags
  240.    * @see ::Flags
  241.    */
  242.   int socketFlags() const;
  243.  
  244.   /**
  245.    * Sets the hostname to the given value. 
  246.    *
  247.    * If this is a listening (passive) socket, the hostname is the host to which the socket
  248.    * will bind in order to listen. If you want to listen in every interface, set it
  249.    * to "*" or QString::null.
  250.    *
  251.    * If this is a connecting (active) socket, the hostname is the host to which we will try
  252.    * to connect.
  253.    *
  254.    * @param host    the hostname
  255.    * @return true on success, false on error
  256.    */
  257.   bool setHost(const QString& host);
  258.  
  259.   /**
  260.    * Returns the hostname.
  261.    * @return the hostname or QString::null if no host has been set
  262.    */
  263.   QString host() const;
  264.  
  265.   /**
  266.    * Sets the port/service.
  267.    * @param port    the port
  268.    */
  269.   bool setPort(int port);
  270.  
  271.   /**
  272.    * Sets the port/service.
  273.    *
  274.    * In the case of Unix-domain sockets, the port is the filename for the socket.
  275.    * If the name is not an absolute path, "/tmp/" will be prepended.
  276.    *
  277.    * @param port    the port
  278.    * @return true if successful, false on error (e.g. connection already established)
  279.    */
  280.   bool setPort(const QString& port);
  281.  
  282.   /**
  283.    * Returns the port/service. If it is a port, the string contains a number.
  284.    * @return the port or QString::null if it has not been set.
  285.    */
  286.   QString port() const;
  287.  
  288.   /**
  289.    * Sets the address where we will connect to.
  290.    *
  291.    * See @ref setHost and @ref setPort for information on the parameters.
  292.    *
  293.    * @param host    the hostname
  294.    * @param port    port number
  295.    * @return true if successful, false on error (e.g. connection already established)
  296.    */
  297.   bool setAddress(const QString& host, int port);
  298.  
  299.   /**
  300.    * Sets the address where we will connect to.
  301.    *
  302.    * See @ref setHost and @ref setPort for information on the parameters.
  303.    *
  304.    * @param host    the hostname
  305.    * @param serv    the service
  306.    * @return true if successful, false on error (e.g. connection already established)
  307.    */
  308.   bool setAddress(const QString& host, const QString& serv);
  309.  
  310.   /**
  311.    * Sets the hostname to which we will bind locally before connecting.
  312.    * @param host    the hostname
  313.    * @return false if this is a passiveSocket, otherwise true.
  314.    */
  315.   bool setBindHost(const QString& host);
  316.  
  317.   /**
  318.    * Unsets the bind hostname. That is, don't request a binding host.
  319.    * @return true if successful, false on error (e.g. connection already established)
  320.    */
  321.   bool unsetBindHost();
  322.  
  323.   /**
  324.    * Returns the hostname to which the socket will be/is bound.
  325.    * @return the host or QString::null if it has not been set.
  326.    */
  327.   QString bindHost() const;
  328.  
  329.   /**
  330.    * Sets the port/service to which we will bind before connecting
  331.    * @param port    the port number
  332.    * @return true if successful, false on error (e.g. connection already established)
  333.    */
  334.   bool setBindPort(int port);
  335.  
  336.   /**
  337.    * Sets the port/service to which we will bind before connecting.
  338.    * @param service    the port number or service name
  339.    * @return true if successful, false on error (e.g. connection already established)
  340.    */
  341.   bool setBindPort(const QString& service);
  342.  
  343.   /**
  344.    * Unsets the bind port/service.
  345.    * @return true if successful, false on error (e.g. connection already established)
  346.    */
  347.   bool unsetBindPort();
  348.  
  349.   /**
  350.    * Returns the service to which the socket will be/is bound.
  351.    * @return the host or QString::null if it has not been set.
  352.    */
  353.   QString bindPort() const;
  354.  
  355.   /**
  356.    * Sets both host and port to which we will bind the socket. Will return
  357.    * false if this is a passiveSocket.
  358.    * @param host    the hostname
  359.    * @param port    the port number
  360.    * @return true if successful, false on error (e.g. connection already established)
  361.    */
  362.   bool setBindAddress(const QString& host, int port);
  363.  
  364.   /**
  365.    * Sets both host and service to which we will bind the socket. Will return
  366.    * false if this is a passiveSocket.
  367.    * @param host    the hostname
  368.    * @param service    the service
  369.    * @return true if successful, false on error (e.g. connection already established)
  370.    */
  371.   bool setBindAddress(const QString& host, const QString& service);
  372.  
  373.   /**
  374.    * Unsets the bind address for the socket. That means that we won't
  375.    * attempt to bind to an address before connecting.
  376.    * @return true if successful, false on error (e.g. connection already established)
  377.    */
  378.   bool unsetBindAddress();
  379.  
  380.   /**
  381.    * Sets the timeout value for the connection (if this is not passiveSocket) or
  382.    * acception (if it is). In the event the given function
  383.    * (connect or accept) returns due to time out, it's possible to call it again.
  384.    *
  385.    * Setting the timeout to 0 disables the timeout feature.
  386.    *
  387.    * @param secs    the timeout length, in seconds
  388.    * @param usecs    the timeout complement, in microseconds
  389.    * @return false if setting timeout makes no sense in the context.
  390.    */
  391.   bool setTimeout(int secs, int usecs = 0);
  392.  
  393.   /**
  394.    * Returns the timeout value for the connection.
  395.    * @return the timeout value. 0 if there is no timeout.
  396.    */
  397.   timeval timeout() const;
  398.  
  399.   /**
  400.    * Sets/unsets blocking mode for the socket. When non-blocking mode is enabled,
  401.    * I/O operations might return error and set errno to EWOULDBLOCK. Also,
  402.    * it's not recommended to use this when using the class signals.
  403.    *
  404.    * @param enable    if true, set blocking mode. False, non-blocking mode.
  405.    * @return false on error.
  406.    */
  407.   bool setBlockingMode(bool enable);
  408.  
  409.   /**
  410.    * Returns the current blocking mode for this socket.
  411.    * @return true if in blocking mode
  412.    */
  413.   bool blockingMode();
  414.  
  415.   /**
  416.    * Sets/unsets address reusing flag for this socket.
  417.    *
  418.    * This function returns true if the value was set correctly. That is NOT
  419.    * the result of the set.
  420.    * @param enable    if true, set address reusable
  421.    * @return true on success, false on failure. If the socket was not yet created,
  422.    * the value is only remembered. In this case the return value is always true.
  423.    */
  424.   bool setAddressReusable(bool enable);
  425.  
  426.   /**
  427.    * Returns whether this socket's address can be reused
  428.    * @return true if the address can be reused
  429.    */
  430.   bool addressReusable();
  431.  
  432.   /**
  433.    * Sets/unsets the v6-only flag for IPv6 sockets.
  434.    *
  435.    * When an IPv6 socket is in use, communication with IPv4 sockets is
  436.    * guaranteed by translating those IPv4 addresses into IPv6 ones
  437.    * (specifically, the v4-mapped addresses). This flag allows that
  438.    * behavior to be turned on and off.
  439.    *
  440.    * Note that this does not have any effect on sockets that are not
  441.    * IPv6 and the function will always return false in those cases.
  442.    * Also note that this flag defaults to off in order to accommodate
  443.    * existing applications.
  444.    *
  445.    * @param enable    if true, no IPv4 translation will be performed;
  446.    *            this socket will be restricted to IPv6 communication
  447.    * @returns true on success, false on failure.
  448.    * @see localAddress to find out if this is an IPv6 socket
  449.    */
  450.   bool setIPv6Only(bool enable);
  451.  
  452.   /**
  453.    * Returns the status of the v6-only flag for IPv6 sockets.
  454.    * @returns true if the flag is set to on; false if it is not. If this
  455.    * socket is not an IPv6 one, the return value is false.
  456.    * @see setIPv6Only
  457.    */
  458.   bool isIPv6Only();
  459.  
  460.   /**
  461.    * Sets the buffer sizes for this socket.
  462.    *
  463.    * This implementation allows any size for both parameters. The value given
  464.    * will be interpreted as the maximum size allowed for the buffers, after
  465.    * which the I/O functions will stop buffering. The value of -1 will be
  466.    * interpreted as "unlimited" size. The value of -2 means "no change".
  467.    *
  468.    * Note: changing the buffer size to 0 for any buffer will cause the given
  469.    * buffer's to be discarded. Likewise, setting the size to a value less than
  470.    * the current size will cause the buffer to be shrunk to the wanted value,
  471.    * as if the data had been read.
  472.    * @param rsize    read buffer size
  473.    * @param wsize    write buffer size
  474.    * @return true on success, false if this is not possible in this state (e.g. connection
  475.    *         not established yet)
  476.    */
  477.   virtual bool setBufferSize(int rsize, int wsize = -2);
  478.  
  479.   /**
  480.    * Returns the local socket address
  481.    * @return the local socket address, can be 0 if the connection has not been established
  482.    *         yet
  483.    */
  484.   const ::KSocketAddress *localAddress();
  485.  
  486.   /**
  487.    * Returns the peer socket address. Use KExtendedSocket::resolve() to
  488.    * resolve this to a human-readable hostname/service or port.
  489.    * @return the peer address, can be 0 if the connection has not been established yet
  490.    *         or the socket is passive
  491.    */
  492.   const ::KSocketAddress *peerAddress();
  493.  
  494.   /**
  495.    * Returns the file descriptor
  496.    * @return the file descriptor. -1 if there is no fd yet.
  497.    */
  498.   inline int fd() const
  499.   { return sockfd; }
  500.  
  501.   /*
  502.    * -- socket creation -- *
  503.    */
  504.  
  505.   /**
  506.    * Performs lookup on the addresses we were given before.
  507.    *
  508.    * This will perform lookups on the bind addresses if they were given.
  509.    * @return 0 or an error. Do not rely on the values returned by lookup
  510.    * as of now. They are not specified.
  511.    */
  512.   virtual int lookup();
  513.  
  514.   /**
  515.    * Starts an asynchronous lookup for the addresses given.
  516.    *
  517.    * When the lookup is done, the lookupReady signal will be emitted.
  518.    *
  519.    * Note that, depending on the parameters for the lookup, this function might
  520.    * know the results without the need for blocking or queuing an
  521.    * asynchronous lookup. That means that the lookupReady signal might be
  522.    * emitted by this function, so your code should be prepared for that.
  523.    *
  524.    * One such case is when noResolve flag is set.
  525.    * If this function is able to determine the results without queuing
  526.    * and the lookup failed, this function will return -1.
  527.    *
  528.    * @return 0 on success or -1 on error. Note that
  529.    * returning 0 means that either we are in the process of doing
  530.    * lookup or that it has finished already.
  531.    */
  532.   virtual int startAsyncLookup();
  533.  
  534.   /**
  535.    * Cancels any on-going asynchronous lookups
  536.    */
  537.   virtual void cancelAsyncLookup();
  538.  
  539.   /**
  540.    * Place the socket in listen mode. The parameters are the same as for
  541.    * the system listen() call.
  542.    * @param N        the queue length for pending connections
  543.    * @return 0 on success, -1 on system error (errno
  544.    *         available) and -2 if this is not a passiveSocket.
  545.    */
  546.   virtual int listen(int N = 5); // 5 is arbitrary
  547.  
  548.   /**
  549.    * Accepts an incoming connection from the socket. If this socket is in
  550.    * blocking mode, this function will block until a connection is received.
  551.    * Otherwise, it might return with error. The sock parameter will be
  552.    * initialised with the newly created socket.
  553.    *
  554.    * Upon successful acception (i.e., this function returns 0), the newly
  555.    * created socket will be already connected. The socket will be unbuffered
  556.    * and readyRead() and readyWrite() signals will be disabled.
  557.    *
  558.    * @param sock    a pointer to an KExtendedSocket variable
  559.    * @return 0 on success, -1 on system error (errno set) and -2 if this is
  560.    * not a passiveSocket and -3 if this took too long (time out)
  561.    */
  562.   virtual int accept(KExtendedSocket *&sock);
  563.  
  564.   /**
  565.    * Attempts to connect to the remote host.
  566.    * After successful connection (return value 0), the socket will be ready
  567.    * for I/O operations. Note, however, that not all signals may be enabled
  568.    * for emission by this socket:
  569.    * @li readyRead and readyWrite signals will be enabled only if
  570.    * enableRead or enableWrite were called. You can still enable
  571.    *    them by calling those functions, of course.
  572.    * @li #closed() will only be sent if we are indeed reading from the input
  573.    *    stream. That is, if this socket is buffering the input. See setBufferSize
  574.    *
  575.    * Note that, in general, functions inherited/overridden from KBufferedIO will only
  576.    * work on buffered sockets, like bytesAvailable and bytesToWrite.
  577.    * @return    The return values are:
  578.    * @li 0: success
  579.    * @li -1: system error, errno was set accordingly
  580.    * @li -2: this socket cannot connect(); this is a passiveSocket. It can also
  581.    *   mean that the function was unable to make a connection with the given
  582.    *   bind address or that an asynchronous connection attempt is already
  583.    *   in progress.
  584.    * @li -3: connection timed out
  585.    *
  586.    */
  587.   virtual int connect();
  588.  
  589.   /**
  590.    * Starts an asynchronous connect. This works exactly the same as #connect,
  591.    * except that the connection result won't be returned.
  592.    *
  593.    * Note that those signals might be emitted before this function returns, so your
  594.    * code should be prepared for that condition.
  595.    *
  596.    * You must call cancelAsyncConnect() before you delete the socket if you
  597.    * call this.  Otherwise you will have crashes.
  598.    *
  599.    * @return 0 on successful queuing of the connect or -1 on error.
  600.    *         If this function returns 0, then the connectionSuccess() or the
  601.    * connectionFailed() signals will be emitted.
  602.    */
  603.   virtual int startAsyncConnect();
  604.  
  605.   /**
  606.    * Cancels any on-going asynchronous connection attempt.
  607.    */
  608.   virtual void cancelAsyncConnect();
  609.  
  610.   /**
  611.    * Implementation of QIODevice::open() pure virtual function.
  612.    * This depends on the target host address already being there.
  613.    * If this is a passiveSocket, this is identical to call listen(); else, if
  614.    * this is not a passiveSocket and no connection attempt is in progress, this
  615.    * is like connect(). If one is in progress, this function will fail.
  616.    * @param mode the open mode. Must be IO_Raw | IO_ReadWrite
  617.    * @return true if successful, false when an error occurred or the most was
  618.    *         not correct
  619.    */
  620.   virtual bool open(int mode = IO_Raw | IO_ReadWrite);
  621.  
  622.   /**
  623.    * Closes the socket. If we have data still in the write buffer yet to be
  624.    * sent, the socket won't be closed right now. It'll be closed after we managed
  625.    * to send everything out.
  626.    * If you want to close the socket now, you may want to call flush() first,
  627.    * and then closeNow().
  628.    */
  629.   virtual void close();
  630.  
  631.   /**
  632.    * Closes the socket now, discarding the contents of the write buffer, if any.
  633.    * The read buffer's contents are kept until they are emptied by read operations
  634.    * or the class is destroyed.
  635.    */
  636.   virtual void closeNow();
  637.  
  638.   /**
  639.    * Releases the socket and anything we have holding on it. The class cannot
  640.    * be used anymore. In other words, this is just like closeNow(), but it does
  641.    * not actually close the socket.
  642.    *
  643.    * This is useful if you just want to connect and don't need the rest of the
  644.    * class.
  645.    *
  646.    * Note that the buffers' contents will be discarded.
  647.    *
  648.    * Use of this method is discouraged, because the socket created might be such that
  649.    * normal library routines can't handle (read, write, close, etc.)
  650.    */
  651.   virtual void release();
  652.  
  653.   /*
  654.    * -- I/O --
  655.    */
  656.  
  657.   /**
  658.    * Flushes the socket buffer. You need not call this method during normal
  659.    * operation as we will try and send everything as soon as possible.
  660.    * However, if you want to make sure that data in the buffer is being sent
  661.    * at this moment, you can call this function. It will try to send as much
  662.    * data as possible, but it will stop as soon as the kernel cannot receive
  663.    * any more data, and would possibly block.
  664.    *
  665.    * By repeatedly calling this function, the behavior will be like that of
  666.    * a blocking socket. Indeed, if this function is called with the kernel not
  667.    * ready to receive data, it will block, unless this is a non-blocking socket.
  668.    *
  669.    * This function does not touch the read buffer. You can empty it by calling
  670.    * readBlock() with a null destination buffer.
  671.    */
  672.   virtual void flush();
  673.  
  674.   /**
  675.    * Returns length of this socket. This call is not supported on sockets.
  676.    * @return the length of this socket, or 0 if unsupported
  677.    */
  678.   virtual inline Q_ULONG size() const
  679.   { return 0; }
  680.  
  681.   /**
  682.    * Returns relative position from start. This call is not supported on sockets.
  683.    * @return the relative position from the start, or 0 if unsupported
  684.    */
  685.   virtual inline Q_ULONG at() const
  686.   { return 0; }
  687.  
  688.   /**
  689.    * Returns true if we are at position. This is not supported on sockets.
  690.    * @param i the position to check
  691.    * @return true if we art at the given position, or always true if unsupported.
  692.    */
  693.   virtual inline bool at(int i)
  694.   { Q_UNUSED(i);return true; }
  695.  
  696.   /**
  697.    * Returns true if we are at the end. This is not supported on sockets, but
  698.    * we always are at the end in a socket...
  699.    * @return true if we are at the end. Always false if unsupported.
  700.    */
  701.   virtual inline bool atEnd() const
  702.   { return false; }
  703.  
  704.   /**
  705.    * Reads a block of data from the socket.
  706.    *
  707.    * If the socket is not buffered, this function will simply call the underlying
  708.    * read method. This function will block if the socket is not on non-blocking mode
  709.    * (see setBlockingMode) and there is not enough data to be read in the
  710.    * Operating System yet. If we are in non-blocking operation, the call will
  711.    * fail in this case.
  712.    *
  713.    * However, if we are buffering, this function will instead read from the
  714.    * buffer while there is available data. This function will never block
  715.    * in buffering mode, which means that if you try to read while the buffers
  716.    * are empty, this function will always return -1 and set the system error to
  717.    * EWOULDBLOCK (aka EAGAIN), so as to mimic non-blocking operation.
  718.    *
  719.    * @param data    where we will write the read data to
  720.    * @param maxlen    maximum length of data to be read
  721.    * @return the number of bytes effectively read, or a negative number in case
  722.    * or an error. If the @p data param is not null, then this is also the number
  723.    * of bytes copied into that buffer. If the return value is different than
  724.    * @p maxlen, then this function encountered a situation in which no more
  725.    * bytes were available. Subsequent calls might cause this function to one
  726.    * of these behaviours:
  727.    * @li return an error, with EWOULDBLOCK system error, if we buffering
  728.    *   or we are in non-blocking mode
  729.    * @li otherwise, it'll block
  730.    * This function returns 0, if the function detected end-of-file condition
  731.    * (socket was closed)
  732.    */
  733.   virtual Q_LONG readBlock(char *data, Q_ULONG maxlen);
  734.  
  735.   /**
  736.    * Writes a block of data to the socket.
  737.    *
  738.    * If the socket is not buffered, this function will simply call the underlying
  739.    * write method. This means that the function might block if that method blocks
  740.    * as well. That situation is possible if we are not in non-blocking mode and
  741.    * the operating system buffers are full for this socket. If we are in
  742.    * non-blocking mode and the operating system buffers are full, this function
  743.    * will return -1 and the system error will be set to EWOULDBLOCK.
  744.    *
  745.    * If we are buffering, this function will simply transfer the data into the
  746.    * write buffer. This function will then always succeed, as long as there is
  747.    * enough room in the buffer. If the buffer size was limited and that limit
  748.    * is reached, this function will copy no more bytes than that limit. Trying
  749.    * to write with a full buffer will return -1 and set system error to
  750.    * EWOULDBLOCK.
  751.    *
  752.    * @param data    the data to write
  753.    * @param len        the length of data to write
  754.    * @return the number of bytes written from @p data buffer.
  755.    * The return value might be less than @p len if the output buffers cannot
  756.    * accommodate that many bytes and -1 in the case of an errro.
  757.    */
  758.   virtual Q_LONG writeBlock(const char *data, Q_ULONG len);
  759.  
  760.   /**
  761.    * Peeks at a block of data from the socket.
  762.    *
  763.    * This is exactly like read, except that the data won't be flushed from the
  764.    * read buffer.
  765.    *
  766.    * If this socket is not buffered, this function will always return with
  767.    * 0 bytes copied.
  768.    *
  769.    * @param data    where to store the data
  770.    * @param maxlen    how many bytes to copy, at most
  771.    * @return the number of bytes copied. 0 does not mean end-of-file
  772.    *         condition.
  773.    */
  774.   virtual int peekBlock(char *data, uint maxlen);
  775.  
  776.   /**
  777.    * Reimplementation of unreadBlock() method. This is so because unreading in
  778.    * sockets doesn't make sense, so this function will always return -1 (error)
  779.    * and set the system error to ENOSYS.
  780.    * @return always -1 (error)
  781.    */
  782.   virtual int unreadBlock(const char *data, uint len);
  783.  
  784.   /**
  785.    * Returns the number of available bytes yet to be read via readBlock
  786.    * and family of functions.
  787.    *
  788.    * Note: as of now, this only works on input-buffered sockets. This will
  789.    * change in the future
  790.    * @return The number of available bytes, or -1 on error or -2 if this call is invalid
  791.    * in the current state.
  792.    */
  793.   virtual int bytesAvailable() const;
  794.  
  795.   /**
  796.    * Waits @p msec milliseconds for more data to be available (use 0 to
  797.    * wait forever). The return value is the amount of data available for
  798.    * read in the read buffer.
  799.    *
  800.    * @param msec    milliseconds to wait
  801.    * @return -1 in case of system error and -2 in case of invalid socket
  802.    *         state
  803.    */
  804.   virtual int waitForMore(int msec);
  805.  
  806.   /**
  807.    * Gets a single character (unsigned char) from the stream.
  808.    * @return the value of the character. Negative if there was an error.
  809.    */
  810.   virtual int getch();
  811.  
  812.   /**
  813.    * Writes a single character (unsigned char) to the stream. All other bits
  814.    * will be ignored.
  815.    * @param ch    character to write, converted to char
  816.    */
  817.   virtual int putch(int ch);
  818.  
  819.   /**
  820.    * Unreads one character from the stream. This is not possible on sockets.
  821.    * @return always returns -1 on sockets.
  822.    */
  823.   virtual int ungetch(int)
  824.   { return -1; }
  825.  
  826.   /**
  827.    * Toggles the emission of the readyRead signal.
  828.    *
  829.    * Note that this signal is emitted every time more data is available to be
  830.    * read, so you might get flooded with it being emitted every time, when in
  831.    * non-buffered mode. However, in buffered mode, this signal will be
  832.    * emitted only when there is data coming in from the wire.
  833.    * By default, this flag is set to false, i.e., signal not being emitted.
  834.    * @param enable    if true, the signal will be emitted
  835.    */
  836.   virtual void enableRead(bool enable);
  837.  
  838.   /**
  839.    * Toggles the emission of the readyWrite signal.
  840.    *
  841.    * Note that this signal is emitted only when the OS is ready to receive more
  842.    * data, which means that the write buffer is empty. And when that is reached,
  843.    * this signal will possibly be emitted on every loop, so you might
  844.    * want to disable it. By default, this flag is set to false.
  845.    * @param enable    if true, the signal will be emitted
  846.    */
  847.   virtual void enableWrite(bool enable);
  848.  
  849. signals:
  850.   /**
  851.    * This signal is emitted whenever an asynchronous lookup process is done.
  852.    * The parameter @p count tells
  853.    * @param count the number of results
  854.    */
  855.   void lookupFinished(int count);
  856.  
  857.   /**
  858.    * This signal is emitted whenever we connected asynchronously to a host.
  859.    */
  860.   void connectionSuccess();
  861.  
  862.   /**
  863.    * This signal is emitted whenever our asynchronous connection attempt
  864.    * failed to all hosts listed.
  865.    * @param error    the errno code of the last connection attempt
  866.    */
  867.   void connectionFailed(int error);
  868.  
  869.   /**
  870.    * This signal is emitted whenever this socket is ready to accept another
  871.    * socket.
  872.    * @see accept()
  873.    */
  874.   void readyAccept();
  875.  
  876. protected:
  877.   int sockfd;            // file descriptor of the socket
  878.  
  879. protected slots:
  880.  
  881.   void socketActivityRead();
  882.   void socketActivityWrite();
  883.   void dnsResultsReady();
  884.   void startAsyncConnectSlot();
  885.   void connectionEvent();
  886.  
  887. protected:
  888.  
  889.   QSocketNotifier *readNotifier();
  890.   QSocketNotifier *writeNotifier();
  891.  
  892. private:
  893.  
  894.   // protection against accidental use
  895.   KExtendedSocket(KExtendedSocket&);
  896.   KExtendedSocket& operator=(KExtendedSocket&);
  897.  
  898.   /**
  899.    * This is actually a wrapper around getaddrinfo().
  900.    * @internal
  901.    */
  902.   static int doLookup(const QString& host, const QString& serv, addrinfo& hint,
  903.               kde_addrinfo** result);
  904.  
  905. protected:
  906.   /**
  907.    * Sets the error code
  908.    */
  909.   void setError(int errorkind, int error);
  910.  
  911.   inline void cleanError()
  912.   { setError(IO_Ok, 0); }
  913.  
  914.   /**
  915.    * Sets the socket status. For derived classes only.
  916.    */
  917.   void setSocketStatus(int status);
  918.  
  919. public:
  920.   /**
  921.    * Performs resolution on the given socket address.
  922.    *
  923.    * That is, tries to resolve the raw form of the socket address into a textual
  924.    * representation.
  925.    *
  926.    * @param sock    the socket address
  927.    * @param len         the length of the socket address
  928.    * @param host    where the hostname will be written
  929.    * @param port    where the service-port will be written
  930.    * @param flags    the same flags as getnameinfo()
  931.    * @returns 0 on success, nonzero otherwise.
  932.    */
  933.   static int resolve(sockaddr* sock, ksocklen_t len, QString& host, QString& port, int flags = 0) KDE_DEPRECATED;
  934.  
  935.   /**
  936.    * Performs resolution on the given socket address.
  937.    *
  938.    * That is, tries to resolve the raw form of the socket address into a textual
  939.    * representation.
  940.    *
  941.    * @param sock    the socket address
  942.    * @param host    where the hostname will be written
  943.    * @param port    where the service-port will be written
  944.    * @param flags    the same flags as getnameinfo()
  945.    * @returns 0 on success, nonzero otherwise.
  946.    */
  947.   static int resolve(::KSocketAddress* sock, QString& host, QString& port, int flags = 0) KDE_DEPRECATED;
  948.  
  949.   /** @deprecated
  950.    * This function is now deprecated. Please use @ref KNetwork::KResolver::resolve.
  951.    *
  952.    * Performs lookup on the given hostname/port combination and returns a list
  953.    * of matching addresses.
  954.    * The error code can be transformed into string by KExtendedSocket::strError()
  955.    * with code of IO_LookupError.
  956.    *
  957.    * IMPORTANT: the result values of the QPtrList must be deleted after use. So,
  958.    * if you don't copy the KAddressInfo objects, the best way to assure that
  959.    * is to call setAutoDelete(true) on the list right after this function
  960.    * returns. If you do copy the results out, you must assure that the objects
  961.    * get deleted when they are not needed any more.
  962.    *
  963.    * @param host    the hostname to look up
  964.    * @param port    the port/service to look up
  965.    * @param flags    flags to be used when looking up, Flags
  966.    * @param error    pointer to a variable holding the error code
  967.    * @return a list of KAddressInfos
  968.    */
  969.   static QPtrList<KAddressInfo> lookup(const QString& host, const QString& port, int flags = 0, int *error = 0) KDE_DEPRECATED;
  970.  
  971.   /**
  972.    * Returns the local socket address
  973.    * Remember to delete the returned object when it is no longer needed.
  974.    * @param fd        the file descriptor
  975.    * @return the local socket address or 0 if an error occurred. Delete after use.
  976.    */
  977.   static ::KSocketAddress *localAddress(int fd) KDE_DEPRECATED;
  978.  
  979.   /**
  980.    * Returns the peer socket address. Use KExtendedSocket::resolve() to
  981.    * resolve this to a human-readable hostname/service or port.
  982.    * Remember to delete the returned object when it is no longer needed.
  983.    * @param fd        the file descriptor
  984.    * @return the peer socket address or 0 if an error occurred. Delete after use.
  985.    */
  986.   static ::KSocketAddress *peerAddress(int fd) KDE_DEPRECATED;
  987.  
  988.   /**
  989.    * Returns the representing text of this error code
  990.    * @param code    the error code, as seen in status()
  991.    * @param syserr    the system error, as from systemError()
  992.    * @return the text for the given error code
  993.    */
  994.   static QString strError(int code, int syserr);
  995.  
  996.   /**
  997.    * Sets/unsets address reusing flag for this socket.
  998.    *
  999.    * This function returns true if the value was set correctly. That is NOT
  1000.    * the result of the set.
  1001.    * @param fd    the file descriptor
  1002.    * @param enable    if true, set address reusable
  1003.    * @return true on success, false on failure.
  1004.    */
  1005.   static bool setAddressReusable(int fd, bool enable) KDE_DEPRECATED;
  1006.  
  1007. protected:
  1008.   virtual void virtual_hook( int id, void* data );
  1009. private:
  1010.   KExtendedSocketPrivate *d;
  1011.  
  1012.   friend class KSocket;
  1013.   friend class KServerSocket;
  1014. };
  1015.  
  1016. /** @deprecated
  1017.  * This class is now deprecated. Please see @ref KNetwork::KResolver for the new API.
  1018.  *
  1019.  * Contains information about an internet address. It wraps addrinfo,
  1020.  * see getaddrinfo(3) for more information.
  1021.  */
  1022. class KDECORE_EXPORT KAddressInfo
  1023. {
  1024. private:
  1025.   addrinfo *ai;
  1026.   ::KSocketAddress *addr;
  1027.  
  1028.   inline KAddressInfo() : ai(0), addr(0)
  1029.   { }
  1030.  
  1031.   //  KAddressInfo(addrinfo *ai);
  1032.   KAddressInfo(KAddressInfo&) { }
  1033.   KAddressInfo& operator=(KAddressInfo&) { return *this; }
  1034.  
  1035. public:
  1036.   ~KAddressInfo();
  1037.  
  1038.   /**
  1039.    * Returns the KAddressInfo's KSocketAddress.
  1040.    * Only valid as long as the KAddressInfo exists.
  1041.    */
  1042.   inline KDE_DEPRECATED operator const ::KSocketAddress*() const 
  1043.   { return addr; }
  1044.  
  1045.   /**
  1046.    * Returns the KAddressInfo's addrinfo.
  1047.    */
  1048.   inline KDE_DEPRECATED operator const addrinfo&() const
  1049.   { return *ai; }
  1050.  
  1051.   /**
  1052.    * Returns a pointer to KAddressInfo's addrinfo.
  1053.    * Only valid as long as the KAddressInfo exists.
  1054.    */
  1055.   inline KDE_DEPRECATED operator const addrinfo*() const
  1056.   { return ai; }
  1057.  
  1058.   /**
  1059.    * Returns the KAddressInfo's KSocketAddress.
  1060.    * Only valid as long as the KAddressInfo exists.
  1061.    * @return the KAddressInfo's KSocketAddress.
  1062.    */
  1063.   inline KDE_DEPRECATED const ::KSocketAddress* address() const
  1064.   { return addr; }
  1065.  
  1066.   /**
  1067.    * Returns the flags of the address info (see getaddrinfo(3)).
  1068.    * @return the flags of the addres info.
  1069.    */
  1070.   int flags() const KDE_DEPRECATED;
  1071.  
  1072.   /**
  1073.    * Returns the family of the address info (see getaddrinfo(3)).
  1074.    * @return the family of the addres info.
  1075.    */
  1076.   int family() const KDE_DEPRECATED;
  1077.  
  1078.   /**
  1079.    * Returns the socket type of the address info (see getaddrinfo(3)).
  1080.    * @return the socket type of the addres info.
  1081.    */
  1082.   int socktype() const KDE_DEPRECATED;
  1083.  
  1084.   /**
  1085.    * Returns the protocol of the address info (see getaddrinfo(3)).
  1086.    * @return the protocol of the addres info.
  1087.    */
  1088.   int protocol() const KDE_DEPRECATED;
  1089.  
  1090.  
  1091.   /**
  1092.    * Returns the official name of the host (see getaddrinfo(3)).
  1093.    * Only valid as long as the KAddressInfo exists.
  1094.    * @return the official name of the host
  1095.    */
  1096.   const char* canonname() const KDE_DEPRECATED;
  1097.  
  1098.   /**
  1099.    * Returns the length of the KSocketAddress.
  1100.    * @return the KSocketAddress's length
  1101.    */
  1102.   inline int length() const
  1103.   { if (addr) return addr->size(); return 0; }
  1104.  
  1105.   friend class KExtendedSocket;
  1106. };
  1107.  
  1108. #endif //Q_OS_UNIX
  1109.  
  1110. #endif // KEXTSOCK_H
  1111.